OpenColorIOΒΆ

Introduction

OpenColorIO (OCIO) is a color management system that allows consistently configuring the various color spaces used in rendering and across other color dependent departments, such as texturing and compositing.

An OCIO configuration defines color spaces and the transformation from a given color space to another. For example, 8 bits color textures are usually stored in the invert-sRGB color space which is non-linear, while illumination computations must be performed in a linear color space, and eventually the resulting image is displayed on a computer screen which usually uses the sRGB color space which is also non-linear. OpenColorIO performs the transformation from the texture color space to the rendering color space to the display color space.

More information on OpenColorIO at https://opencolorio.org.

For compatibility and historic reasons, Guerilla refers to color spaces as Gamma.

The following diagrams shows how colors, coming from input files as textures or mattes or from the color picker, and going to output files and screen, are transformed into and from the Rendering color space:

Setup

Guerilla looks for the OCIO configuration file in the following order:

  • Preferences -> Project Settings -> OCIO -> OCIO Configuration File
  • Using the OCIO environment variable.
  • In ocio/config.ocio in the Guerilla installation directory.

By default, Guerilla provides a configuration file for general sRGB color management.

Use a custom configuration for all my projects

  • You can set the OCIO environment variable to the location of your config.ocio file, prior to running Guerilla.

    • Use a custom configuration for a specific project

    • You can set the Preferences -> Project Settings -> OCIO -> OCIO Configuration File attribute in the Guerilla project.

      • The Project Settings OCIO configuration. Values inherited from the the configuration file are shown in grey.

      Roles

      OCIO defines roles as aliases for color spaces. For instance, you can set texture to use a specific color space (sRGB, for instance) or to use the texture_paint role and alias the sRGB color space to texture_paint.

      This is handy to switch from an OCIO configuration to another, where color spaces names would be different.

      Roles are usually defined directly in the config.ocio file, but you can override them in Guerilla, using the Preferences -> Project Settings -> OCIO tab.

      Guerilla natively uses the following roles:

      • rendering: the rendering colorspace. If the rendering role is not defined, Guerilla falls back on the scene_linear role, and eventually on the linear role/color space.
      • color_picking: the color picker viewing color space. Colors picked using the color picker are automatically converted into the rendering color space.
      • data: the colorspace for non color data, such as positions, normals. Data colorspaces usually won't involve color transformation.
      • texture_int_paint: the default color space for integer input color textures.
      • texture_float_paint: the default color space for half/float input color textures.
      • texture_paint: the color space for input color textures.

      Changing the rendering color space after picking a color will not adjust the color to the new color space. You must adjust it manually.

      Display Views

      OCIO defines color transforms for displays, which can be used directly in the top-right drop down list of the Render View.

      The Display Views selector from the Render View

      When left empty, Guerilla looks for an adequate role or colorspace in the following order:
      • the srgb_equivalent role
      • the sRGB color space (found in the Guerilla default config.ocio)
      • the Output - sRGB color space (found in ACES)
      • and eventually, the rendering color space
      This way, Guerilla tries to stick to an sRGB monitor.

      Textures

      Color textures (such as Diffuse Color, etc.) have a proper color space and are converted at render time to the internal Rendering color space, so it is necessary to specify the correct texture color space for textures to have to correct aspect.

      By default, all color texture shaders are set to the empty string and left for Guerilla to select at run-time.

      When left empty, Guerilla looks for an adequate role or colorspace depending on the type of texture (8/16 bits integer or half/float) in the following order for 8/16 bits integer:
      • the texture_int_paint role
      • the srgb_equivalent role
      • the sRGB color space (found in the Guerilla default config.ocio)
      • the Utility - sRGB - Texture color space (found in ACES)
      • eventually, the texture_paint role
      And in the following order for half/float:
      • the texture_float_paint role
      • eventually, the texture_paint role
       Customize the texture_paint role for a specific project

      • Set the Preferences -> Project Settings -> OCIO -> Texture Paint attribute in the Guerilla project to a specific color space.

      Overriding the texture_paint role from the Project Settings

      Adjusting the Color Space of a texture

      • Select the shader to adjust
      • Select the correct color space from the Gamma attribute

      Overriding the Texture shader Gamma attributes

      Rendered Images

      The color space of rendered images can be set directly in the Render Settings -> File -> Gamma attribute of the RenderPass.

      When left empty, Guerilla looks for an adequate role or colorspace, depending on the bit depth of the output. For integer (8/16 bits) outputs:
      • the srgb_equivalent role
      • the sRGB color space (found in the Guerilla default config.ocio)
      • the Output - sRGB color space (found in ACES)
      • and eventually, the rendering color space
      Half/float outputs use by default the rendering color space.

      Setting the RenderPass Gamma attributes

      Individual AOVs can have their proper Gamma setting, and will use the same rule as RenderPass.

      sRGB Color Management

      This is the most classic scenario, and Guerilla provides a simple configuration to deal with it. By default, the configuration set texture_int_paint to sRGB, which is correct for 8/16 bits color textures, and texture_float_paint to linear, which correct for half/float color textures.

      Since, by default, color texture lookups use an empty string color space, Guerilla will use the texture_int_paint and texture_float_paint roles, based on the texture type.

      ACES Color Management

      The Academy Color Encoding System comes with an OCIO configuration file which can be found here: https://github.com/imageworks/OpenColorIO-Configs.

      The ACES uses a wide gammut base color space which encompasses a large variety of devices, such as cameras, monitors, etc. It more reliably represents a wide range of colors, and avoids problematic out-of sRGB range values (negative colors, hdr) which would show up when strictly using sRGB.

      Display on a sRGB monitor

      Use the sRGB Display View in the top right drop down list of the Render View. Note that your image will appear darker compared to the default Guerilla OCIO configuration, because ACES sRGB Display View accounts for the high dynamic potential of the ACES color spaces, and a 1-white point maps to a less than white on the screen, thus allowing a perceived higher range of light dynamics.

      Textures

      The ACES OCIO configurations doesn't provide texture_int_paint and texture_float_paint roles, so integer textures will fallback on the Utility - sRGB - Texture color space. Float textures will fallback on the texture_paint role, which is the ACES - ACEScc color space by default (ACES 1.0.3.)

      Use 8/16 bits sRGB textures with ACES

      There is nothing particular to do. To enforce sRGB textures, choose Utility - sRGB - Texture in the texture_int_paint role.

      Use half/float sRGB textures with ACES

      Simply switch the texture_float_paint role to the lin_srgb color space.

      Legacy

      Project Gamma

      For compatibility reasons with previous versions of Guerilla, you can enable using the legacy Project Gamma by checking the Project Settings -> OCIO -> Use Project Gamma.

      In effect, this overrides the default OCIO role with the Project Gamma value, and input/output colorspaces which were left to the default Project Gamma value will automatically and properly use the default role.

      Missing Color Spaces

      To help transitionning from previous color management to OCIO, Guerilla has a few hardcoded fallbacks that allows looking up the current color configuration when stumbling upon a missing color space.

      "sRGB" falls back to:

      • "Input - Generic - sRGB - Texture" as in ACES configs
      • "vd16" as in spi-anim config
      • "srgb8" as in spi-vfx config
      • "sRGB OETF" as in Filmic Blender config

      "linear" falls back to the rendering color space.